/*
 * $Id: search.h,v 1.2 2005-12-11 15:49:11 bacon Exp $
 */

#ifndef _XP_BAS_SEARCH_H_
#define _XP_BAS_SEARCH_H_

#include <xp/types.h>
#include <xp/macros.h>

/*
 * TYPE: xp_search_compare_t
 *   Defines a comparison method for search functions
 * 
 * DESCRITION:
 *   Each comparision method should return 0 if *item1* and *item2* are 
 *   euqal, a positive integer if *item1* is greater than *item2*, a negative 
 *   if *item2* is greater than *item1*. Both *item1* and *item2* are pointers 
 *   to any two items in the array. *user_data* which is a pointer to 
 *   user-defined data passed to the search function is passed to the 
 *   comparision method as it is. It should be conformant to the following 
 *   prototype.
 *
 *   int compar (const void* item1, const void* item2, void* user_data);
 */
typedef int (*xp_search_compare_t) (const void*, const void*, void*);

#ifdef __cplusplus
extern "C" {
#endif

/* 
 * FUNCTION: xp_bsearch 
 *   Searches a sorted array
 *
 * PARAMETERS:
 *   key - [in]
 *   base - [in]
 *   nmemb - [in]
 *   size - [in]
 *   arg - [in]
 *   compar - [in]
 *
 * RETURNS:
 *   Pointer to a matching item of the array if a match if found. *XP_NULL* otherwise.
 *
 * SEE ALSO:
 *   <xp_lsearch>
 */
void* xp_bsearch (
	const void *key, const void *base, xp_size_t nmemb,
	xp_size_t size, void* arg, xp_search_compare_t compar);

/* 
 * FUNCTION: xp_lsearch 
 *   Searches an array
 *
 * RETURNS:
 *   Pointer to a matching item of the array if a match if found. *XP_NULL* otherwise.
 *
 * SEE ALSO:
 *   <xp_bsearch>
 */
void* xp_lsearch (
	const void *key, const void *base, xp_size_t nmemb,
	xp_size_t size, void* arg, xp_search_compare_t compar);

#ifdef __cplusplus
}
#endif

#endif
